home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / gaim / blist.h < prev    next >
C/C++ Source or Header  |  2005-10-18  |  27KB  |  902 lines
  1. /**
  2.  * @file blist.h Buddy List API
  3.  * @ingroup core
  4.  *
  5.  * gaim
  6.  *
  7.  * Gaim is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25. #ifndef _GAIM_BLIST_H_
  26. #define _GAIM_BLIST_H_
  27.  
  28. /* I can't believe I let ChipX86 inspire me to write good code. -Sean */
  29.  
  30. #include <glib.h>
  31.  
  32. typedef struct _GaimBuddyList GaimBuddyList;
  33. typedef struct _GaimBlistUiOps GaimBlistUiOps;
  34. typedef struct _GaimBlistNode GaimBlistNode;
  35.  
  36. typedef struct _GaimBlistNodeAction GaimBlistNodeAction;
  37.  
  38. typedef struct _GaimChat GaimChat;
  39. typedef struct _GaimGroup GaimGroup;
  40. typedef struct _GaimContact GaimContact;
  41. typedef struct _GaimBuddy GaimBuddy;
  42.  
  43. #include "account.h"
  44. #include "buddyicon.h"
  45.  
  46. /**************************************************************************/
  47. /* Enumerations                                                           */
  48. /**************************************************************************/
  49. typedef enum
  50. {
  51.     GAIM_BLIST_GROUP_NODE,
  52.     GAIM_BLIST_CONTACT_NODE,
  53.     GAIM_BLIST_BUDDY_NODE,
  54.     GAIM_BLIST_CHAT_NODE,
  55.     GAIM_BLIST_OTHER_NODE
  56.  
  57. } GaimBlistNodeType;
  58.  
  59. #define GAIM_BLIST_NODE_IS_CHAT(n) ((n)->type == GAIM_BLIST_CHAT_NODE)
  60. #define GAIM_BLIST_NODE_IS_BUDDY(n) ((n)->type == GAIM_BLIST_BUDDY_NODE)
  61. #define GAIM_BLIST_NODE_IS_CONTACT(n) ((n)->type == GAIM_BLIST_CONTACT_NODE)
  62. #define GAIM_BLIST_NODE_IS_GROUP(n) ((n)->type == GAIM_BLIST_GROUP_NODE)
  63.  
  64. typedef enum
  65. {
  66.     GAIM_BUDDY_SIGNING_OFF = -1,
  67.     GAIM_BUDDY_OFFLINE = 0,
  68.     GAIM_BUDDY_ONLINE,
  69.     GAIM_BUDDY_SIGNING_ON
  70.  
  71. } GaimBuddyPresenceState;
  72.  
  73. #define GAIM_BUDDY_IS_ONLINE(b) ((b)->account->gc && \
  74.         ((b)->present == GAIM_BUDDY_ONLINE || \
  75.          (b)->present == GAIM_BUDDY_SIGNING_ON))
  76.  
  77. typedef enum
  78. {
  79.     GAIM_BLIST_NODE_FLAG_NO_SAVE = 1,    /**< node should not be saved with the buddy list */
  80. } GaimBlistNodeFlags;
  81.  
  82. #define GAIM_BLIST_NODE_HAS_FLAG(b, f) ((b)->flags & (f))
  83. #define GAIM_BLIST_NODE_SHOULD_SAVE(b) (! GAIM_BLIST_NODE_HAS_FLAG(b, GAIM_BLIST_NODE_FLAG_NO_SAVE))
  84.  
  85.  
  86. /**************************************************************************/
  87. /* Data Structures                                                        */
  88. /**************************************************************************/
  89.  
  90. /**
  91.  * A Buddy list node.  This can represent a group, a buddy, or anything else.  This is a base class for struct buddy and
  92.  * struct group and for anything else that wants to put itself in the buddy list. */
  93. struct _GaimBlistNode {
  94.     GaimBlistNodeType type;             /**< The type of node this is       */
  95.     GaimBlistNode *prev;                /**< The sibling before this buddy. */
  96.     GaimBlistNode *next;                /**< The sibling after this buddy.  */
  97.     GaimBlistNode *parent;              /**< The parent of this node        */
  98.     GaimBlistNode *child;               /**< The child of this node         */
  99.     GHashTable *settings;               /**< per-node settings              */
  100.     void          *ui_data;             /**< The UI can put data here.      */
  101.     GaimBlistNodeFlags flags;           /**< The buddy flags                */
  102. };
  103.  
  104. /**
  105.  * A buddy.  This contains everything Gaim will ever need to know about someone on the buddy list.  Everything.
  106.  */
  107. struct _GaimBuddy {
  108.     GaimBlistNode node;                     /**< The node that this buddy inherits from */
  109.     char *name;                             /**< The screenname of the buddy. */
  110.     char *alias;                            /**< The user-set alias of the buddy */
  111.     char *server_alias;                     /**< The server-specified alias of the buddy.  (i.e. MSN "Friendly Names") */
  112.     GaimBuddyPresenceState present;         /**< This is 0 if the buddy appears offline, 1 if he appears online, and 2 if
  113.                             he has recently signed on */
  114.     int evil;                               /**< The warning level */
  115.     time_t signon;                          /**< The time the buddy signed on. */
  116.     int idle;                               /**< The time the buddy has been idle in minutes. */
  117.     int uc;                                 /**< This is a cryptic bitmask that makes sense only to the prpl.  This will get changed */
  118.     void *proto_data;                       /**< This allows the prpl to associate whatever data it wants with a buddy */
  119.     GaimBuddyIcon *icon;                    /**< The buddy icon. */
  120.     GaimAccount *account;               /**< the account this buddy belongs to */
  121.     guint timer;                /**< The timer handle. */
  122. };
  123.  
  124. /**
  125.  * A contact.  This contains everything Gaim will ever need to know about a contact.
  126.  */
  127. struct _GaimContact {
  128.     GaimBlistNode node;        /**< The node that this contact inherits from. */
  129.     char *alias;            /**< The user-set alias of the contact */
  130.     int totalsize;            /**< The number of buddies in this contact */
  131.     int currentsize;        /**< The number of buddies in this contact corresponding to online accounts */
  132.     int online;                /**< The number of buddies in this contact who are currently online */
  133.     GaimBuddy *priority;    /**< The "top" buddy for this contact */
  134. };
  135.  
  136.  
  137. /**
  138.  * A group.  This contains everything Gaim will ever need to know about a group.
  139.  */
  140. struct _GaimGroup {
  141.     GaimBlistNode node;                    /**< The node that this group inherits from */
  142.     char *name;                            /**< The name of this group. */
  143.     int totalsize;                   /**< The number of chats and contacts in this group */
  144.     int currentsize;               /**< The number of chats and contacts in this group corresponding to online accounts */
  145.     int online;                   /**< The number of chats and contacts in this group who are currently online */
  146. };
  147.  
  148. /**
  149.  * A chat.  This contains everything Gaim needs to put a chat room in the
  150.  * buddy list.
  151.  */
  152. struct _GaimChat {
  153.     GaimBlistNode node;      /**< The node that this chat inherits from */
  154.     char *alias;             /**< The display name of this chat. */
  155.     GHashTable *components;  /**< the stuff the protocol needs to know to join the chat */
  156.     GaimAccount *account; /**< The account this chat is attached to */
  157. };
  158.  
  159.  
  160. /**
  161.  * The Buddy List
  162.  */
  163. struct _GaimBuddyList {
  164.     GaimBlistNode *root;          /**< The first node in the buddy list */
  165.     GHashTable *buddies;          /**< Every buddy in this list */
  166.     GaimBlistUiOps *ui_ops;       /**< The UI operations for the buddy list */
  167.  
  168.     void *ui_data;                /**< UI-specific data. */
  169. };
  170.  
  171. /**
  172.  * Buddy list UI operations.
  173.  *
  174.  * Any UI representing a buddy list must assign a filled-out GaimBlistUiOps
  175.  * structure to the buddy list core.
  176.  */
  177. struct _GaimBlistUiOps
  178. {
  179.     void (*new_list)(GaimBuddyList *list); /**< Sets UI-specific data on a buddy list. */
  180.     void (*new_node)(GaimBlistNode *node);      /**< Sets UI-specific data on a node. */
  181.     void (*show)(GaimBuddyList *list);     /**< The core will call this when its finished doing it's core stuff */
  182.     void (*update)(GaimBuddyList *list,
  183.                GaimBlistNode *node);            /**< This will update a node in the buddy list. */
  184.     void (*remove)(GaimBuddyList *list,
  185.                GaimBlistNode *node);            /**< This removes a node from the list */
  186.     void (*destroy)(GaimBuddyList *list);  /**< When the list gets destroyed, this gets called to destroy the UI. */
  187.     void (*set_visible)(GaimBuddyList *list,
  188.                 gboolean show);             /**< Hides or unhides the buddy list */
  189.     void (*request_add_buddy)(GaimAccount *account, const char *username,
  190.                               const char *group, const char *alias);
  191.     void (*request_add_chat)(GaimAccount *account, GaimGroup *group, 
  192.                              const char *alias, const char *name);
  193.     void (*request_add_group)(void);
  194. };
  195.  
  196.  
  197. struct _GaimBlistNodeAction {
  198.     char *label;
  199.     void (*callback)(GaimBlistNode *, gpointer);
  200.     gpointer data;
  201. };
  202.  
  203.  
  204. #ifdef __cplusplus
  205. extern "C" {
  206. #endif
  207.  
  208. /**************************************************************************/
  209. /** @name Buddy List API                                                  */
  210. /**************************************************************************/
  211. /*@{*/
  212.  
  213. /**
  214.  * Creates a new buddy list
  215.  */
  216. GaimBuddyList *gaim_blist_new();
  217.  
  218. /**
  219.  * Sets the main buddy list.
  220.  *
  221.  * @return The main buddy list.
  222.  */
  223. void gaim_set_blist(GaimBuddyList *blist);
  224.  
  225. /**
  226.  * Returns the main buddy list.
  227.  *
  228.  * @return The main buddy list.
  229.  */
  230. GaimBuddyList *gaim_get_blist(void);
  231.  
  232. /**
  233.  * Shows the buddy list, creating a new one if necessary.
  234.  *
  235.  */
  236. void gaim_blist_show();
  237.  
  238.  
  239. /**
  240.  * Destroys the buddy list window.
  241.  */
  242. void gaim_blist_destroy();
  243.  
  244. /**
  245.  * Hides or unhides the buddy list.
  246.  *
  247.  * @param show   Whether or not to show the buddy list
  248.  */
  249. void gaim_blist_set_visible(gboolean show);
  250.  
  251. /**
  252.  * Updates a buddy's status.
  253.  *
  254.  * This needs to not take an int.
  255.  *
  256.  * @param buddy   The buddy whose status has changed
  257.  * @param status  The new status in cryptic prpl-understood code
  258.  */
  259. void gaim_blist_update_buddy_status(GaimBuddy *buddy, int status);
  260.  
  261.  
  262. /**
  263.  * Updates a buddy's presence.
  264.  *
  265.  * @param buddy    The buddy whose presence has changed
  266.  * @param online   If the buddy is now online
  267.  */
  268. void gaim_blist_update_buddy_presence(GaimBuddy *buddy, gboolean online);
  269.  
  270. /**
  271.  * Updates a buddy's signon time.
  272.  *
  273.  * @param buddy  The buddy whose idle time has changed.
  274.  * @param signon The buddy's signon time since the dawn of the UNIX epoch.
  275.  */
  276. void gaim_blist_update_buddy_signon(GaimBuddy *buddy, time_t signon);
  277.  
  278. /**
  279.  * Updates a buddy's idle time.
  280.  *
  281.  * @param buddy  The buddy whose idle time has changed
  282.  * @param idle   The buddy's idle time in minutes.
  283.  */
  284. void gaim_blist_update_buddy_idle(GaimBuddy *buddy, int idle);
  285.  
  286.  
  287. /**
  288.  * Updates a buddy's warning level.
  289.  *
  290.  * @param buddy   The buddy whose warning level has changed.
  291.  * @param warning The warning level as an int from 0 to 100.
  292.  */
  293. void gaim_blist_update_buddy_evil(GaimBuddy *buddy, int warning);
  294.  
  295. /**
  296.  * Updates a buddy's icon.
  297.  *
  298.  * @param buddy  The buddy whose buddy icon has changed
  299.  */
  300. void gaim_blist_update_buddy_icon(GaimBuddy *buddy);
  301.  
  302. /**
  303.  * Renames a buddy in the buddy list.
  304.  *
  305.  * @param buddy  The buddy whose name will be changed.
  306.  * @param name   The new name of the buddy.
  307.  */
  308. void gaim_blist_rename_buddy(GaimBuddy *buddy, const char *name);
  309.  
  310.  
  311. /**
  312.  * Aliases a buddy in the buddy list.
  313.  *
  314.  * @param buddy  The buddy whose alias will be changed.
  315.  * @param alias  The buddy's alias.
  316.  */
  317. void gaim_blist_alias_buddy(GaimBuddy *buddy, const char *alias);
  318.  
  319. /**
  320.  * Sets the server-sent alias of a buddy in the buddy list.
  321.  *
  322.  * @param buddy  The buddy whose alias will be changed.
  323.  * @param alias  The buddy's "official" alias.
  324.  */
  325. void gaim_blist_server_alias_buddy(GaimBuddy *buddy, const char *alias);
  326.  
  327. /**
  328.  * Aliases a chat in the buddy list.
  329.  *
  330.  * @param chat  The chat whose alias will be changed.
  331.  * @param alias The chat's new alias.
  332.  */
  333. void gaim_blist_alias_chat(GaimChat *chat, const char *alias);
  334.  
  335. /**
  336.  * Renames a group
  337.  *
  338.  * @param group  The group to rename
  339.  * @param name   The new name
  340.  */
  341. void gaim_blist_rename_group(GaimGroup *group, const char *name);
  342.  
  343. /**
  344.  * Creates a new chat for the buddy list
  345.  *
  346.  * @param account    The account this chat will get added to
  347.  * @param alias      The alias of the new chat
  348.  * @param components The info the prpl needs to join the chat
  349.  * @return           A newly allocated chat
  350.  */
  351. GaimChat *gaim_chat_new(GaimAccount *account, const char *alias, GHashTable *components);
  352.  
  353. /**
  354.  * Gets the alias of the chat, or the chat name if the alias does not exist
  355.  *
  356.  * @param chat    The chat
  357.  * @return        The display name of the chat
  358.  */
  359. char *gaim_chat_get_display_name(GaimChat *chat);
  360.  
  361. /**
  362.  * Adds a new chat to the buddy list.
  363.  *
  364.  * The chat will be inserted right after node or appended to the end
  365.  * of group if node is NULL.  If both are NULL, the buddy will be added to
  366.  * the "Chats" group.
  367.  *
  368.  * @param chat  The new chat who gets added
  369.  * @param group  The group to add the new chat to.
  370.  * @param node   The insertion point
  371.  */
  372. void gaim_blist_add_chat(GaimChat *chat, GaimGroup *group, GaimBlistNode *node);
  373.  
  374. /**
  375.  * Creates a new buddy
  376.  *
  377.  * @param account    The account this buddy will get added to
  378.  * @param screenname The screenname of the new buddy
  379.  * @param alias      The alias of the new buddy (or NULL if unaliased)
  380.  * @return           A newly allocated buddy
  381.  */
  382. GaimBuddy *gaim_buddy_new(GaimAccount *account, const char *screenname, const char *alias);
  383.  
  384. /**
  385.  * Sets a buddy's icon.
  386.  *
  387.  * This should only be called from within Gaim. You probably want to
  388.  * call gaim_buddy_icon_set_data().
  389.  *
  390.  * @param buddy The buddy.
  391.  * @param icon  The buddy icon.
  392.  *
  393.  * @see gaim_buddy_icon_set_data()
  394.  */
  395. void gaim_buddy_set_icon(GaimBuddy *buddy, GaimBuddyIcon *icon);
  396.  
  397. /**
  398.  * Returns a buddy's icon.
  399.  *
  400.  * @param buddy The buddy.
  401.  *
  402.  * @return The buddy icon.
  403.  */
  404. GaimBuddyIcon *gaim_buddy_get_icon(const GaimBuddy *buddy);
  405.  
  406. /**
  407.  * Returns a buddy's contact.
  408.  *
  409.  * @param buddy The buddy.
  410.  *
  411.  * @return The buddy's contact.
  412.  */
  413. GaimContact *gaim_buddy_get_contact(GaimBuddy *buddy);
  414.  
  415. /**
  416.  * Adds a new buddy to the buddy list.
  417.  *
  418.  * The buddy will be inserted right after node or prepended to the
  419.  * group if node is NULL.  If both are NULL, the buddy will be added to
  420.  * the "Buddies" group.
  421.  *
  422.  * @param buddy   The new buddy who gets added
  423.  * @param contact The optional contact to place the buddy in.
  424.  * @param group   The group to add the new buddy to.
  425.  * @param node    The insertion point
  426.  */
  427. void gaim_blist_add_buddy(GaimBuddy *buddy, GaimContact *contact, GaimGroup *group, GaimBlistNode *node);
  428.  
  429. /**
  430.  * Creates a new group
  431.  *
  432.  * You can't have more than one group with the same name.  Sorry.  If you pass
  433.  * this the * name of a group that already exists, it will return that group.
  434.  *
  435.  * @param name   The name of the new group
  436.  * @return       A new group struct
  437. */
  438. GaimGroup *gaim_group_new(const char *name);
  439.  
  440. /**
  441.  * Adds a new group to the buddy list.
  442.  *
  443.  * The new group will be inserted after insert or prepended to the list if
  444.  * node is NULL.
  445.  *
  446.  * @param group  The group
  447.  * @param node   The insertion point
  448.  */
  449. void gaim_blist_add_group(GaimGroup *group, GaimBlistNode *node);
  450.  
  451. /**
  452.  * Creates a new contact
  453.  *
  454.  * @return       A new contact struct
  455.  */
  456. GaimContact *gaim_contact_new();
  457.  
  458. /**
  459.  * Adds a new contact to the buddy list.
  460.  *
  461.  * The new contact will be inserted after insert or prepended to the list if
  462.  * node is NULL.
  463.  *
  464.  * @param contact The contact
  465.  * @param group   The group to add the contact to
  466.  * @param node    The insertion point
  467.  */
  468. void gaim_blist_add_contact(GaimContact *contact, GaimGroup *group, GaimBlistNode *node);
  469.  
  470. /**
  471.  * Merges two contacts
  472.  *
  473.  * All of the buddies from source will be moved to target
  474.  *
  475.  * @param source  The contact to merge
  476.  * @param node    The place to merge to (a buddy or contact)
  477.  */
  478. void gaim_blist_merge_contact(GaimContact *source, GaimBlistNode *node);
  479.  
  480. /**
  481.  * Returns the highest priority buddy for a given contact.
  482.  *
  483.  * @param contact  The contact
  484.  * @return The highest priority buddy
  485.  */
  486. GaimBuddy *gaim_contact_get_priority_buddy(GaimContact *contact);
  487.  
  488. /**
  489.  * Sets the alias for a contact.
  490.  *
  491.  * @param contact  The contact
  492.  * @param alias    The alias to set, or NULL to unset
  493.  */
  494. void gaim_contact_set_alias(GaimContact *contact, const char *alias);
  495.  
  496. /**
  497.  * Gets the alias for a contact.
  498.  *
  499.  * @param contact  The contact
  500.  * @return  The alias, or NULL if it is not set.
  501.  */
  502. const char *gaim_contact_get_alias(GaimContact *contact);
  503.  
  504. /**
  505.  * Determines whether an account owns any buddies in a given contact
  506.  *
  507.  * @param contact  The contact to search through.
  508.  * @param account  The account.
  509.  *
  510.  * @return TRUE if there are any buddies from account in the contact, or FALSE otherwise.
  511.  */
  512. gboolean gaim_contact_on_account(GaimContact *contact, GaimAccount *account);
  513.  
  514.  
  515. /**
  516.  * Removes a buddy from the buddy list and frees the memory allocated to it.
  517.  *
  518.  * @param buddy   The buddy to be removed
  519.  */
  520. void gaim_blist_remove_buddy(GaimBuddy *buddy);
  521.  
  522. /**
  523.  * Removes a contact, and any buddies it contains, and frees the memory
  524.  * allocated to it.
  525.  *
  526.  * @param contact The contact to be removed
  527.  */
  528. void gaim_blist_remove_contact(GaimContact *contact);
  529.  
  530. /**
  531.  * Removes a chat from the buddy list and frees the memory allocated to it.
  532.  *
  533.  * @param chat   The chat to be removed
  534.  */
  535. void gaim_blist_remove_chat(GaimChat *chat);
  536.  
  537. /**
  538.  * Removes a group from the buddy list and frees the memory allocated to it and to
  539.  * its children
  540.  *
  541.  * @param group   The group to be removed
  542.  */
  543. void gaim_blist_remove_group(GaimGroup *group);
  544.  
  545. /**
  546.  * Returns the alias of a buddy.
  547.  *
  548.  * @param buddy   The buddy whose name will be returned.
  549.  * @return        The alias (if set), server alias (if set and preference
  550.  *                is to display server aliases), or NULL.
  551.  */
  552. const char *gaim_buddy_get_alias_only(GaimBuddy *buddy);
  553.  
  554.  
  555. /**
  556.  * Returns the correct name to display for a buddy, taking the contact alias
  557.  * into account. In order of precedence: the buddy's alias; the buddy's
  558.  * contact alias; the buddy's server alias; the buddy's user name.
  559.  *
  560.  * @param buddy  The buddy whose name will be returned
  561.  * @return       The appropriate name or alias, or NULL.
  562.  *
  563.  */
  564. const char *gaim_buddy_get_contact_alias(GaimBuddy *buddy);
  565.  
  566.  
  567. /**
  568.  * Returns the correct name to display for a buddy. In order of precedence:
  569.  * the buddy's alias; the buddy's server alias; the buddy's contact alias;
  570.  * the buddy's user name.
  571.  *
  572.  * @param buddy   The buddy whose name will be returned.
  573.  * @return        The appropriate name or alias, or NULL
  574.  */
  575. const char *gaim_buddy_get_alias(GaimBuddy *buddy);
  576.  
  577. /**
  578.  * Returns the correct name to display for a blist chat.
  579.  *
  580.  * @param chat   The chat whose name will be returned.
  581.  * @return       The alias (if set), or first component value.
  582.  */
  583. const char *gaim_chat_get_name(GaimChat *chat);
  584.  
  585. /**
  586.  * Finds the buddy struct given a screenname and an account
  587.  *
  588.  * @param name    The buddy's screenname
  589.  * @param account The account this buddy belongs to
  590.  * @return        The buddy or NULL if the buddy does not exist
  591.  */
  592. GaimBuddy *gaim_find_buddy(GaimAccount *account, const char *name);
  593.  
  594. /**
  595.  * Finds the buddy struct given a screenname, an account, and a group
  596.  *
  597.  * @param name    The buddy's screenname
  598.  * @param account The account this buddy belongs to
  599.  * @param group   The group to look in
  600.  * @return        The buddy or NULL if the buddy does not exist in the group
  601.  */
  602. GaimBuddy *gaim_find_buddy_in_group(GaimAccount *account, const char *name,
  603.         GaimGroup *group);
  604.  
  605. /**
  606.  * Finds all GaimBuddy structs given a screenname and an account
  607.  *
  608.  * @param name    The buddy's screenname
  609.  * @param account The account this buddy belongs to
  610.  *
  611.  * @return        A GSList of buddies (which must be freed), or NULL if the buddy doesn't exist
  612.  */
  613. GSList *gaim_find_buddies(GaimAccount *account, const char *name);
  614.  
  615.  
  616. /**
  617.  * Finds a group by name
  618.  *
  619.  * @param name    The groups name
  620.  * @return        The group or NULL if the group does not exist
  621.  */
  622. GaimGroup *gaim_find_group(const char *name);
  623.  
  624. /**
  625.  * Finds a chat by name.
  626.  *
  627.  * @param account The chat's account.
  628.  * @param name    The chat's name.
  629.  *
  630.  * @return The chat, or @c NULL if the chat does not exist.
  631.  */
  632. GaimChat *gaim_blist_find_chat(GaimAccount *account, const char *name);
  633.  
  634. /**
  635.  * Returns the group of which the chat is a member.
  636.  *
  637.  * @param chat The chat.
  638.  *
  639.  * @return The parent group, or @c NULL if the chat is not in a group.
  640.  */
  641. GaimGroup *gaim_chat_get_group(GaimChat *chat);
  642.  
  643. /**
  644.  * Returns the group of which the buddy is a member.
  645.  *
  646.  * @param buddy   The buddy
  647.  * @return        The group or NULL if the buddy is not in a group
  648.  */
  649. GaimGroup *gaim_find_buddys_group(GaimBuddy *buddy);
  650.  
  651.  
  652. /**
  653.  * Returns a list of accounts that have buddies in this group
  654.  *
  655.  * @param g The group
  656.  *
  657.  * @return A list of gaim_accounts
  658.  */
  659. GSList *gaim_group_get_accounts(GaimGroup *g);
  660.  
  661. /**
  662.  * Determines whether an account owns any buddies in a given group
  663.  *
  664.  * @param g       The group to search through.
  665.  * @param account The account.
  666.  *
  667.  * @return TRUE if there are any buddies in the group, or FALSE otherwise.
  668.  */
  669. gboolean gaim_group_on_account(GaimGroup *g, GaimAccount *account);
  670.  
  671. /**
  672.  * Called when an account gets signed on.  Tells the UI to update all the
  673.  * buddies.
  674.  *
  675.  * @param account   The account
  676.  */
  677. void gaim_blist_add_account(GaimAccount *account);
  678.  
  679.  
  680. /**
  681.  * Called when an account gets signed off.  Sets the presence of all the buddies to 0
  682.  * and tells the UI to update them.
  683.  *
  684.  * @param account   The account
  685.  */
  686. void gaim_blist_remove_account(GaimAccount *account);
  687.  
  688.  
  689. /**
  690.  * Determines the total size of a group
  691.  *
  692.  * @param group  The group
  693.  * @param offline Count buddies in offline accounts
  694.  * @return The number of buddies in the group
  695.  */
  696. int gaim_blist_get_group_size(GaimGroup *group, gboolean offline);
  697.  
  698. /**
  699.  * Determines the number of online buddies in a group
  700.  *
  701.  * @param group The group
  702.  * @return The number of online buddies in the group, or 0 if the group is NULL
  703.  */
  704. int gaim_blist_get_group_online_count(GaimGroup *group);
  705.  
  706. /*@}*/
  707.  
  708. /****************************************************************************************/
  709. /** @name Buddy list file management API                                                */
  710. /****************************************************************************************/
  711.  
  712. /*@{*/
  713. /**
  714.  * Force an immediate write of the buddy list.  Normally the buddy list is
  715.  * saved automatically a few seconds after a change is made.
  716.  */
  717. void gaim_blist_sync();
  718.  
  719. /**
  720.  * Loads the buddy list from ~/.gaim/blist.xml.
  721.  */
  722. void gaim_blist_load();
  723.  
  724. /**
  725.  * Schedule a save of the blist.xml file.  This is used by the privacy
  726.  * API whenever the privacy settings are changed.  If you make a change
  727.  * to blist.xml using one of the functions in the buddy list API, then
  728.  * the buddy list is saved automatically, so you should not need to
  729.  * call this.
  730.  */
  731. void gaim_blist_schedule_save();
  732.  
  733. /**
  734.  * Requests from the user information needed to add a buddy to the
  735.  * buddy list.
  736.  *
  737.  * @param account  The account the buddy is added to.
  738.  * @param username The username of the buddy.
  739.  * @param group    The name of the group to place the buddy in.
  740.  * @param alias    The optional alias for the buddy.
  741.  */
  742. void gaim_blist_request_add_buddy(GaimAccount *account, const char *username,
  743.                                   const char *group, const char *alias);
  744.  
  745. /**
  746.  * Requests from the user information needed to add a chat to the
  747.  * buddy list.
  748.  *
  749.  * @param account The account the buddy is added to.
  750.  * @param group   The optional group to add the chat to.
  751.  * @param alias   The optional alias for the chat.
  752.  * @param name    The required chat name.
  753.  */
  754. void gaim_blist_request_add_chat(GaimAccount *account, GaimGroup *group,
  755.                                  const char *alias, const char *name);
  756.  
  757. /**
  758.  * Requests from the user information needed to add a group to the
  759.  * buddy list.
  760.  */
  761. void gaim_blist_request_add_group(void);
  762.  
  763. /**
  764.  * Associates a boolean with a node in the buddy list
  765.  *
  766.  * @param node  The node to associate the data with
  767.  * @param key   The identifier for the data
  768.  * @param value The value to set
  769.  */
  770. void gaim_blist_node_set_bool(GaimBlistNode *node, const char *key, gboolean value);
  771.  
  772. /**
  773.  * Retrieves a named boolean setting from a node in the buddy list
  774.  *
  775.  * @param node  The node to retrieve the data from
  776.  * @param key   The identifier of the data
  777.  *
  778.  * @return The value, or FALSE if there is no setting
  779.  */
  780. gboolean gaim_blist_node_get_bool(GaimBlistNode *node, const char *key);
  781.  
  782. /**
  783.  * Associates an integer with a node in the buddy list
  784.  *
  785.  * @param node  The node to associate the data with
  786.  * @param key   The identifier for the data
  787.  * @param value The value to set
  788.  */
  789. void gaim_blist_node_set_int(GaimBlistNode *node, const char *key, int value);
  790.  
  791. /**
  792.  * Retrieves a named integer setting from a node in the buddy list
  793.  *
  794.  * @param node  The node to retrieve the data from
  795.  * @param key   The identifier of the data
  796.  *
  797.  * @return The value, or 0 if there is no setting
  798.  */
  799. int gaim_blist_node_get_int(GaimBlistNode *node, const char *key);
  800.  
  801. /**
  802.  * Associates a string with a node in the buddy list
  803.  *
  804.  * @param node  The node to associate the data with
  805.  * @param key   The identifier for the data
  806.  * @param value The value to set
  807.  */
  808. void gaim_blist_node_set_string(GaimBlistNode *node, const char *key,
  809.         const char *value);
  810.  
  811. /**
  812.  * Retrieves a named string setting from a node in the buddy list
  813.  *
  814.  * @param node  The node to retrieve the data from
  815.  * @param key   The identifier of the data
  816.  *
  817.  * @return The value, or NULL if there is no setting
  818.  */
  819. const char *gaim_blist_node_get_string(GaimBlistNode *node, const char *key);
  820.  
  821. /**
  822.  * Removes a named setting from a blist node
  823.  *
  824.  * @param node  The node from which to remove the setting
  825.  * @param key   The name of the setting
  826.  */
  827. void gaim_blist_node_remove_setting(GaimBlistNode *node, const char *key);
  828.  
  829. /*@}*/
  830.  
  831.  
  832. /**
  833.  * Retrieves the extended menu items for a buddy list node.
  834.  * @param n    The blist node for which to obtain the extended menu items.
  835.  * @return    list of GaimBlistNodeAction items, as harvested by the
  836.  *        blist-node-extended-menu signal.
  837.  */
  838. GList *gaim_blist_node_get_extended_menu(GaimBlistNode *n);
  839.  
  840.  
  841. /**
  842.  * Creates a new GaimBlistNodeAction.
  843.  * @param label        The text label to display for this action.
  844.  * @param callback    The function to be called when the action is used on
  845.  *            a selected GaimBlistNode.
  846.  * @param data        Additional data, to be passed to the callback
  847.  */
  848. GaimBlistNodeAction  *gaim_blist_node_action_new(char *label,
  849.         void (*callback)(GaimBlistNode *, gpointer), gpointer data);
  850.  
  851.  
  852. /**************************************************************************/
  853. /** @name UI Registration Functions                                       */
  854. /**************************************************************************/
  855. /*@{*/
  856.  
  857. /**
  858.  * Sets the UI operations structure to be used for the buddy list.
  859.  *
  860.  * @param ops The ops struct.
  861.  */
  862. void gaim_blist_set_ui_ops(GaimBlistUiOps *ops);
  863.  
  864. /**
  865.  * Returns the UI operations structure to be used for the buddy list.
  866.  *
  867.  * @return The UI operations structure.
  868.  */
  869. GaimBlistUiOps *gaim_blist_get_ui_ops(void);
  870.  
  871. /*@}*/
  872.  
  873. /**************************************************************************/
  874. /** @name Buddy List Subsystem                                            */
  875. /**************************************************************************/
  876. /*@{*/
  877.  
  878. /**
  879.  * Returns the handle for the buddy list subsystem.
  880.  *
  881.  * @return The buddy list subsystem handle.
  882.  */
  883. void *gaim_blist_get_handle(void);
  884.  
  885. /**
  886.  * Initializes the buddy list subsystem.
  887.  */
  888. void gaim_blist_init(void);
  889.  
  890. /**
  891.  * Uninitializes the buddy list subsystem.
  892.  */
  893. void gaim_blist_uninit(void);
  894.  
  895. /*@}*/
  896.  
  897. #ifdef __cplusplus
  898. }
  899. #endif
  900.  
  901. #endif /* _GAIM_BLIST_H_ */
  902.